{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-03T17:54:01.000017Z",
     "start_time": "2019-09-03T17:54:00.916960Z"
    }
   },
   "source": [
    "<h1 align=\"center\">\n",
    "    <a href=\"https://github.com/ml-tooling/ml-workspace\" title=\"ML Workspace Home\">\n",
    "    <img width=50% alt=\"\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/ml-workspace-logo.png\"></a>\n",
    "</h1>\n",
    "\n",
    "<div align=\"center\">\n",
    "    <strong>All-in-one web-based development environment for machine learning</strong>\n",
    "</div>\n",
    "<br>\n",
    "<div align=\"center\"><div style=\"display: inline-flex;\">\n",
    "    <a href=\"https://hub.docker.com/r/mltooling/ml-workspace\" title=\"Docker Pulls\"><img  src=\"https://img.shields.io/docker/pulls/mltooling/ml-workspace.svg\"></a>\n",
    "    <a href=\"https://hub.docker.com/r/mltooling/ml-workspace\" title=\"Docker Image Metadata\"><img style=\"margin-left: 5px;\" src=\"https://images.microbadger.com/badges/image/mltooling/ml-workspace.svg\"></a>\n",
    "     <a href=\"https://github.com/ml-tooling/ml-workspace/issues\" title=\"Open Issues\"><img style=\"margin-left: 5px;\"  src=\"https://img.shields.io/github/issues/ml-tooling/ml-workspace\"></a>\n",
    "    <a href=\"https://gitter.im/ml-tooling/ml-workspace\" title=\"Chat on Gitter\"><img style=\"margin-left: 5px;\" src=\"https://badges.gitter.im/ml-tooling/ml-workspace.svg\"></a>\n",
    "    <a href=\"https://github.com/ml-tooling/ml-workspace\" title=\"ML Workspace Github Stars\"><img style=\"margin-left: 5px;\" src=\"https://img.shields.io/github/stars/ml-tooling/ml-workspace?style=social\"></a>\n",
    "    <a href=\"https://twitter.com/mltooling\" title=\"ML Tooling on Twitter\"><img style=\"margin-left: 5px;\" src=\"https://img.shields.io/twitter/follow/mltooling.svg?style=social\"></a>\n",
    "</div></div>\n",
    "<br>\n",
    "<div align=\"center\">\n",
    "  <a href=\"#Features\">Features & Screenshots</a> •\n",
    "  <a href=\"#Support\">Support</a> •\n",
    "  <a href=\"https://github.com/ml-tooling/ml-workspace/issues/new?labels=bug&template=01_bug-report.md\">Report a Bug</a> •\n",
    "  <a href=\"https://github.com/ml-tooling/ml-workspace\">Github Repo</a> •\n",
    "  <a href=\"https://github.com/ml-tooling/ml-workspace#faq\">FAQ</a> •\n",
    "  <a href=\"https://github.com/ml-tooling/ml-workspace#known-issues\">Known Issues</a> •\n",
    "  <a href=\"#Next-Steps\">Next Steps</a>\n",
    "</div>\n",
    "\n",
    "The ML workspace is an all-in-one web-based IDE specialized for machine learning and data science. It is simple to deploy and gets you started within minutes to productively built ML solutions on your own machines. This workspace is the ultimate tool for developers preloaded with a variety of popular data science libraries (e.g., Tensorflow, PyTorch, Keras, Sklearn) and dev tools (e.g., Jupyter, VS Code, Tensorboard) perfectly configured, optimized, and integrated.\n",
    "\n",
    "## Highlights\n",
    "\n",
    "- 💫 Jupyter, JupyterLab, and Visual Studio Code web-based IDEs.\n",
    "- 🗃 Pre-installed with many popular data science libraries & tools.\n",
    "- 🖥 Full Linux desktop GUI accessible via web browser.\n",
    "- 🔀 Seamless Git integration optimized for notebooks.\n",
    "- 📈 Integrated hardware & training monitoring via Tensorboard & Netdata.\n",
    "- 🚪 Access from anywhere via Web, SSH, or VNC under a single port.\n",
    "- 🎛 Usable as remote kernel (Jupyter) or remote machine (VS Code) via SSH.\n",
    "- 🐳 Easy to deploy on Mac, Linux, and Windows via Docker."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-03T18:07:54.987457Z",
     "start_time": "2019-09-03T18:07:54.909305Z"
    }
   },
   "source": [
    "## Features"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div align=\"center\">\n",
    "  <a href=\"#Jupyter\">Jupyter</a> •\n",
    "  <a href=\"#Desktop-GUI\">Desktop GUI</a> •\n",
    "  <a href=\"#Visual-Studio-Code\">VS Code</a> •\n",
    "  <a href=\"#JupyterLab\">JupyterLab</a> •\n",
    "  <a href=\"#Git-Integration\">Git Integration</a> •\n",
    "  <a href=\"#File-Sharing\">File Sharing</a> •\n",
    "  <a href=\"#Access-Ports\">Access Ports</a> •\n",
    "  <a href=\"#Tensorboard\">Tensorboard</a> •\n",
    "  <a href=\"#Extensibility\">Extensibility</a> •\n",
    "  <a href=\"#Hardware-Monitoring\">Hardware Monitoring</a> •\n",
    "  <a href=\"#SSH-Access\">SSH Access</a> •\n",
    "  <a href=\"#Remote-Development\">Remote Development</a> •\n",
    "  <a href=\"#Run-as-a-job\">Job Execution</a>\n",
    "</div>\n",
    "\n",
    "The workspace is equipped with a selection of best-in-class open-source development tools to help with the machine learning workflow. Many of these tools can be started from the `Open Tool` menu from Jupyter (the main application of the workspace):\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/open-tools.png\"/>\n",
    "\n",
    "### Install Anything\n",
    "\n",
    "Within your workspace you have **full root & sudo privileges** to install any library or tool you need via terminal (e.g., `pip`, `apt-get`, `conda`, or `npm`). You can find more ways to extend the workspace within the [Extensibility](#Extensibility) section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-03T18:09:27.684126Z",
     "start_time": "2019-09-03T18:09:19.197848Z"
    }
   },
   "outputs": [],
   "source": [
    "!pip install matplotlib-venn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Install Dependencies in Notebooks:</b> It’s a good idea to include cells which install and load any custom  libraries or files (which are not pre-installed in the workspace) that your notebook needs.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Jupyter\n",
    "\n",
    "[Jupyter Notebook](https://jupyter.org/) is a web-based interactive environment for writing and running code. The main building blocks of Jupyter are the file-browser, the notebook editor, and kernels. The file-browser provides an interactive file manager for all notebooks, files, and folders in the `/workspace` directory.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/jupyter-tree.png\"/>\n",
    "\n",
    "A new notebook can be created by clicking on the `New` drop-down button at the top of the list and selecting the desired language kernel.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "You can spawn interactive <b>terminal</b> instances as well by selecting <code>New -> Terminal</code> in the file-browser.\n",
    "</div>\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/jupyter-notebook.png\"/>\n",
    "\n",
    "The notebook editor enables users to author documents that include live code, markdown text, shell commands, LaTeX equations, interactive widgets, plots, and images. These notebook documents provide a complete and self-contained record of a computation that can be converted to various formats and shared with others.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "This workspace has a variety of <b>third-party Jupyter extensions</b> activated. You can configure these extensions in the nbextensions configurator: <b>nbextensions</b> tab on the file browser\n",
    "</div>\n",
    "\n",
    "The Notebook allows code to be run in a range of different programming languages. For each notebook document that a user opens, the web application starts a **kernel** that runs the code for that notebook and returns output. This workspace has a Python 3 and Python 2 kernel pre-installed. Additional Kernels can be installed to get access to other languages (e.g., R, Scala, Go) or additional computing resources (e.g., GPUs, CPUs, Memory).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "<b>Python 2</b> support is deprecated and not fully supported. Please only use Python 2 if necessary!\n",
    "</div>\n",
    "\n",
    "### Desktop GUI\n",
    "\n",
    "This workspace provides an HTTP-based VNC access to the workspace via [noVNC](https://github.com/novnc/noVNC). Thereby, you can access and work within the workspace with a fully-featured desktop GUI. To access this desktop GUI, go to `Open Tool`, select `VNC`, and click the `Connect` button. In the case you are asked for a password, use `vncpassword`.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/desktop-vnc.png\"/>\n",
    "\n",
    "Once you are connected, you will see a desktop GUI that allows you to install and use full-fledged web-browsers or any other tool that is available for Ubuntu. Within the `Tools` folder on the desktop, you will find a collection of install scripts that makes it straightforward to install some of the most commonly used development tools, such as Atom, PyCharm, R-Runtime, R-Studio, or Postman (just double-click on the script).\n",
    "\n",
    "**Clipboard:** If you want to share the clipboard between your machine and the workspace, you can use the copy-paste functionality as described below:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/desktop-vnc-clipboard.png\"/>\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "<b>Long-running tasks:</b> Use the desktop GUI for long-running Jupyter executions. By running notebooks from the browser of your workspace desktop GUI, all output will be synchronized to the notebook even if you have disconnected your browser from the notebook.\n",
    "</div>\n",
    "\n",
    "### Visual Studio Code\n",
    "\n",
    "[Visual Studio Code](https://github.com/microsoft/vscode) (`Open Tool -> VS Code`) is an open-source lightweight but powerful code editor with built-in support for a variety of languages and a rich ecosystem of extensions. It combines the simplicity of a source code editor with powerful developer tooling, like IntelliSense code completion and debugging. The workspace integrates VS Code as a web-based application accessible through the browser-based on the awesome [code-server](https://github.com/cdr/code-server) project. It allows you to customize every feature to your liking and install any number of third-party extensions.\n",
    "\n",
    "<p align=\"center\"><img src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/vs-code.png\"/></p>\n",
    "\n",
    "The workspace also provides a VS Code integration into Jupyter allowing you to open a VS Code instance for any selected folder, as shown below:\n",
    "\n",
    "<p align=\"center\"><img src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/vs-code-open.png\"/></p>\n",
    "\n",
    "### JupyterLab\n",
    "\n",
    "[JupyterLab](https://github.com/jupyterlab/jupyterlab) (`Open Tool -> JupyterLab`) is the next-generation user interface for Project Jupyter. It offers all the familiar building blocks of the classic Jupyter Notebook (notebook, terminal, text editor, file browser, rich outputs, etc.) in a flexible and powerful user interface. This JupyterLab instance comes pre-installed with a few helpful extensions such as a the [jupyterlab-toc](https://github.com/jupyterlab/jupyterlab-toc), [jupyterlab-git](https://github.com/jupyterlab/jupyterlab-git), and [juptyterlab-tensorboard](https://github.com/chaoleili/jupyterlab_tensorboard).\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/jupyterlab.png\"/>\n",
    "\n",
    "### Git Integration\n",
    "\n",
    "Version control is a crucial aspect of productive collaboration. To make this process as smooth as possible, we have integrated a custom-made Jupyter extension specialized on pushing single notebooks, a full-fledged web-based Git client ([ungit](https://github.com/FredrikNoren/ungit)), a tool to open and edit plain text documents (e.g., `.py`, `.md`) as notebooks ([jupytext](https://github.com/mwouts/jupytext)), as well as a notebook merging tool ([nbdime](https://github.com/jupyter/nbdime)). Additionally, JupyterLab and VS Code also provide GUI-based Git clients.\n",
    "\n",
    "#### Clone Repository\n",
    "\n",
    "For cloning repositories via `https`, we recommend to navigate to the desired root folder and to click on the `git` button as shown below:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/git-open.png\"/>\n",
    "\n",
    "This might ask for some required settings and, subsequently, opens [ungit](https://github.com/FredrikNoren/ungit), a web-based Git client with a clean and intuitive UI that makes it convenient to sync your code artifacts. Within ungit, you can clone any repository. If authentication is required, you will get asked for your credentials.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/git-ungit-credentials.png\"/>\n",
    "\n",
    "#### Push, Pull, Merge, and Other Git Actions\n",
    "\n",
    "To commit and push a single notebook to a remote Git repository, we recommend to use the Git plugin integrated into Jupyter, as shown below:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/git-push-notebook.png\"/>\n",
    "\n",
    "For more advanced Git operations, we recommend to use [ungit](https://github.com/FredrikNoren/ungit). With ungit, you can do most of the common git actions such as push, pull, merge, branch, tag, checkout, and many more.\n",
    "\n",
    "#### Diffing and Merging Notebooks\n",
    "\n",
    "Jupyter notebooks are great, but they often are huge files, with a very specific JSON file format. To enable seamless diffing and merging via Git this workspace is pre-installed with [nbdime](https://github.com/jupyter/nbdime). Nbdime understands the structure of notebook documents and, therefore, automatically makes intelligent decisions when diffing and merging notebooks. In the case you have merge conflicts, nbdime will make sure that the notebook is still readable by Jupyter, as shown below:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/git-nbdime-merging.png\"/>\n",
    "\n",
    "Furthermore, the workspace comes pre-installed with [jupytext](https://github.com/mwouts/jupytext), a Jupyter plugin that reads and writes notebooks as plain text files. This allows you to open, edit, and run scripts or markdown files (e.g., `.py`, `.md`) as notebooks within Jupyter. In the following screenshot, we have opened a markdown file via Jupyter:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/git-jupytext.png\"/>\n",
    "\n",
    "In combination with Git, jupytext enables a clear diff history and easy merging of version conflicts. With both of those tools, collaborating on Jupyter notebooks with Git becomes straightforward.\n",
    "\n",
    "### File Sharing\n",
    "\n",
    "The workspace has a feature to share any file or folder with anyone via a token-protected link. To share data via a link, select any file or folder from the Jupyter directory tree and click on the share button as shown in the following screenshot:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/file-sharing-open.png\"/>\n",
    "\n",
    "This will generate a unique link protected via a token that gives anyone with the link access to view and download the selected data via the [Filebrowser](https://github.com/filebrowser/filebrowser) UI:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/file-sharing-filebrowser.png\"/>\n",
    "\n",
    "To deactivate or manage (e.g., provide edit permissions) shared links, open the Filebrowser via `Open Tool -> Filebrowser` and select `Settings->User Management`.\n",
    "\n",
    "### Access Ports\n",
    "\n",
    "It is possible to securely access any workspace internal port by selecting `Open Tool -> Access Port`. With this feature, you are able to access a REST API or web application running inside the workspace directly with your browser. The feature enables developers  to build, run, test, and debug REST APIs or web applications directly from the workspace.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/access-port.png\"/>\n",
    "\n",
    "If you want to use an HTTP client or share access to a given port, you can select the `Get shareable link` option. This generates a token-secured link that anyone with access to the link can use to access the specified port.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "The HTTP app requires to be resolved from a relative URL path or configure a base path (<code>/tools/PORT/</code>).\n",
    "</div>\n",
    "\n",
    "<details>\n",
    "\n",
    "<summary>Example (click to expand...)</summary>\n",
    "\n",
    "1. Start an HTTP server on port `1234` by running this command in a terminal within the workspace: `python -m http.server 1234`\n",
    "2. Select `Open Tool -> Access Port`, input port `1234`, and select the `Get shareable link` option.\n",
    "3. Click `Access`, and you will see the content provided by Python's `http.server`.\n",
    "4. The opened link can also be shared to other people or called from external applications (e.g., try with Incognito Mode in Chrome).\n",
    "\n",
    "</details>\n",
    "\n",
    "### SSH Access\n",
    "\n",
    "SSH provides a powerful set of features that enables you to be more productive with your development tasks. You can easily set up a secure and passwordless SSH connection to a workspace by selecting `Open Tool -> SSH`. This will generate a secure setup command that can be run on any Linux or Mac machine to configure a passwordless & secure SSH connection to the workspace. Alternatively, you can also download the setup script and run it (instead of using the command).\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/ssh-access.png\"/>\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "The setup script only runs on Mac and Linux. Windows is currently not supported.\n",
    "</div>\n",
    "\n",
    "Just run the setup command or script on the machine from where you want to setup a connection to the workspace and input a name for the connection (e.g., `my-workspace`). You might also get asked for some additional input during the process, e.g. to install a remote kernel if `remote_ikernel` is installed. Once the passwordless SSH connection is successfully setup and tested, you can securely connect to the workspace by simply executing `ssh my-workspace`.\n",
    "\n",
    "Besides the ability to execute commands on a remote machine, SSH also provides a variety of other features that can improve your development workflow as described in the following sections.\n",
    "\n",
    "<details>\n",
    "<summary><b>Tunnel Ports</b> (click to expand...)</summary>\n",
    "\n",
    "An SSH connection can be used for tunneling application ports from the remote machine to the local machine, or vice versa. For example, you can expose the workspace internal port `5901` (VNC Server) to the local machine on port `5000` by executing:\n",
    "\n",
    "```bash\n",
    "ssh -nNT -L 5000:localhost:5901 my-workspace\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "To expose an application port from your local machine to a workspace, use the <code>-R</code> option (instead of <code>-L</code>).\n",
    "</div>\n",
    "\n",
    "After the tunnel is established, you can use your favorite VNC viewer on your local machine and connect to `vnc://localhost:5000` (default password: `vncpassword`). To make the tunnel connection more resistant and reliable, we recommend to use [autossh](https://www.harding.motd.ca/autossh/) to automatically restart SSH tunnels in the case that the connection dies:\n",
    "\n",
    "```bash\n",
    "autossh -M 0 -f -nNT -L 5000:localhost:5901 my-workspace\n",
    "```\n",
    "\n",
    "Port tunneling is quite useful when you have started any server-based tool within the workspace that you like to make accessible for another machine. In its default setting, the workspace has a variety of tools already running on different ports, such as:\n",
    "\n",
    "- `8080`: Main workspace port with access to all integrated tools.\n",
    "- `8090`: Jupyter server.\n",
    "- `8054`: VS Code server.\n",
    "- `5901`: VNC server.\n",
    "- `3389`: RDP server.\n",
    "- `22`: SSH server.\n",
    "\n",
    "You can find port information on all the tools in the [supervisor configuration](https://github.com/ml-tooling/ml-workspace/blob/master/resources/config/supervisord.conf).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "📖 For more information about port tunneling/forwarding, we recommend <a href=\"https://www.everythingcli.org/ssh-tunnelling-for-fun-and-profit-local-vs-remote\">this guide</a>.\n",
    "</div>\n",
    "<br>\n",
    "</details>\n",
    "\n",
    "<details>\n",
    "<summary><b>Copy Data via SCP</b> (click to expand...)</summary>\n",
    "\n",
    "[SCP](https://linux.die.net/man/1/scp) allows files and directories to be securely copied to, from, or between different machines via SSH connections. For example, to copy a local file (`./local-file.txt`) into the `/workspace` folder inside the workspace, execute:\n",
    "\n",
    "```bash\n",
    "scp ./local-file.txt my-workspace:/workspace\n",
    "```\n",
    "\n",
    "To copy the `/workspace` directory from `my-workspace` to the working directory of the local machine, execute:\n",
    "\n",
    "```bash\n",
    "scp -r my-workspace:/workspace .\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "📖 For more information about scp, we recommend <a href=\"https://www.garron.me/en/articles/scp.html\">this guide</a>.\n",
    "</div>\n",
    "<br>\n",
    "</details>\n",
    "\n",
    "<details>\n",
    "<summary><b>Sync Data via Rsync</b> (click to expand...)</summary>\n",
    "\n",
    "[Rsync](https://linux.die.net/man/1/rsync) is a utility for efficiently transferring and synchronizing files between different machines (e.g., via SSH connections) by comparing the modification times and sizes of files. The rsync command will determine which files need to be updated each time it is run, which is far more efficient and convenient than using something like scp or sftp. For example, to sync all content of a local folder (`./local-project-folder/`) into the `/workspace/remote-project-folder/` folder inside the workspace, execute:\n",
    "\n",
    "```bash\n",
    "rsync -rlptzvP --delete --exclude=\".git\" \"./local-project-folder/\" \"my-workspace:/workspace/remote-project-folder/\"\n",
    "```\n",
    "\n",
    "If you have some changes inside the folder on the workspace, you can sync those changes back to the local folder by changing the source and destination arguments:\n",
    "\n",
    "```bash\n",
    "rsync -rlptzvP --delete --exclude=\".git\" \"my-workspace:/workspace/remote-project-folder/\" \"./local-project-folder/\"\n",
    "```\n",
    "\n",
    "You can rerun these commands each time you want to synchronize the latest copy of your files. Rsync will make sure that only updates will be transferred.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "📖 You can find more information about rsync on <a href=\"https://linux.die.net/man/1/rsync\">this man page</a>.\n",
    "</div>\n",
    "<br>\n",
    "</details>\n",
    "\n",
    "<details>\n",
    "<summary><b>Mount Folders via SSHFS</b> (click to expand...)</summary>\n",
    "\n",
    "Besides copying and syncing data, an SSH connection can also be used to mount directories from a remote machine into the local filesystem via [SSHFS](https://github.com/libfuse/sshfs). \n",
    "For example, to mount the `/workspace` directory of `my-workspace` into a local path (e.g. `/local/folder/path`), execute:\n",
    "\n",
    "```bash\n",
    "sshfs -o reconnect my-workspace:/workspace /local/folder/path\n",
    "```\n",
    "\n",
    "Once the remote directory is mounted, you can interact with the remote file system the same way as with any local directory and file.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "📖 For more information about sshfs, we recommend <a href=\"https://www.digitalocean.com/community/tutorials/how-to-use-sshfs-to-mount-remote-file-systems-over-ssh\">this guide</a>.\n",
    "</div>\n",
    "<br>\n",
    "</details>\n",
    "\n",
    "### Remote Development\n",
    "\n",
    "The workspace can be integrated and used as a remote runtime (also known as remote kernel/machine/interpreter) for a variety of popular development tools and IDEs, such as Jupyter, VS Code, PyCharm, Colab, or Atom Hydrogen. Thereby, you can connect your favorite development tool running on your local machine to a remote machine for code execution. This enables a **local-quality development experience with remote-hosted compute resources**.\n",
    "\n",
    "These integrations usually require a passwordless SSH connection from the local machine to the workspace. To set up an SSH connection, please follow the steps explained in the [SSH Access](#ssh-access) section.\n",
    "\n",
    "<details>\n",
    "<summary><b>Jupyter - Remote Kernel</b> (click to expand...)</summary>\n",
    "\n",
    "The workspace can be added to a Jupyter instance as a remote kernel by using the [remote_ikernel](https://bitbucket.org/tdaff/remote_ikernel/) tool. If you have installed remote_ikernel (`pip install remote_ikernel`) on your local machine, the SSH setup script of the workspace will automatically offer you the option to setup a remote kernel connection.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "When running kernels on remote machines, the notebooks themselves will be saved onto the local filesystem, but the kernel will only have access to the filesystem of the remote machine running the kernel. If you need to sync data, you can make use of rsync, scp, or sshfs as explained in the <a href=\"#SSH-Access\">SSH Access</a> section.\n",
    "</div>\n",
    "\n",
    "In case you want to manually setup and manage remote kernels, use the [remote_ikernel](https://bitbucket.org/tdaff/remote_ikernel/src/default/README.rst) command-line tool, as shown below:\n",
    "\n",
    "```bash\n",
    "# Change my-workspace with the name of a workspace SSH connection\n",
    "remote_ikernel manage --add \\\n",
    "    --interface=ssh \\\n",
    "    --kernel_cmd=\"ipython kernel -f {connection_file}\" \\\n",
    "    --name=\"ml-server Py 3.6\" \\\n",
    "    --host=\"my-workspace\"\n",
    "```\n",
    "\n",
    "You can use the remote_ikernel command line functionality to list (`remote_ikernel manage --show`) or delete (`remote_ikernel manage --delete <REMOTE_KERNEL_NAME>`) remote kernel connections.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/remote-dev-jupyter-kernel.png\"/>\n",
    "\n",
    "</details>\n",
    "\n",
    "<details>\n",
    "<summary><b>VS Code - Remote Machine</b> (click to expand...)</summary>\n",
    "\n",
    "The Visual Studio Code [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension allows you to open a remote folder on any remote machine with SSH access and work with it just as you would if the folder were on your own machine. Once connected to a remote machine, you can interact with files and folders anywhere on the remote filesystem and take full advantage of VS Code's feature set (IntelliSense, debugging, and extension support). The discovers and works out-of-the-box with passwordless SSH connections as configured by the workspace SSH setup script. To enable your local VS Code application to connect to a workspace:\n",
    "\n",
    "1. Install [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension inside your local VS Code.\n",
    "2. Run the SSH setup script of a selected workspace as explained in the [SSH Access](#ssh-access) section.\n",
    "3. Open the Remote-SSH panel in your local VS Code. All configured SSH connections should be automatically discovered. Just select any configured workspace connection you like to connect to as shown below:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/remote-dev-vscode.gif\"/>\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "📖 You can find additional features and information about the Remote SSH extension in <a href=\"https://code.visualstudio.com/docs/remote/ssh\">this guide</a>.\n",
    "</div>\n",
    "<br>\n",
    "</details>\n",
    "\n",
    "### Tensorboard\n",
    "\n",
    "[Tensorboard](https://www.tensorflow.org/tensorboard) provides a suite of visualization tools to make it easier to understand, debug, and optimize your experiment runs. It includes logging features for scalar, histogram, model structure, embeddings, and text & image visualization. The workspace comes pre-installed with [jupyter_tensorboard extension](https://github.com/lspvic/jupyter_tensorboard) that integrates Tensorboard into the Jupyter interface with functionalities to start, manage, and stop instances. You can open a new instance for a valid logs directory, as shown below:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/tensorboard-open.png\" />\n",
    "\n",
    "If you have opened a Tensorboard instance in a valid log directory, you will see the visualizations of your logged data:\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/tensorboard-dashboard.png\" />\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "Tensorboard can be used in combination with many other ML frameworks besides Tensorflow. By using the  <a href=\"https://github.com/lanpa/tensorboardX\">tensorboardX</a> library you can log basically from any python based library. Also, PyTorch has a direct Tensorboard integration as described <a href=\"https://pytorch.org/docs/stable/tensorboard.html\">here</a>.\n",
    "</div>\n",
    "\n",
    "If you prefer to see the tensorboard directly within your notebook, you can make use of following **Jupyter magic**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-03T18:34:48.570782Z",
     "start_time": "2019-09-03T18:34:48.426150Z"
    }
   },
   "outputs": [],
   "source": [
    "%load_ext tensorboard.notebook\n",
    "%tensorboard --logdir /workspace/path/to/logs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hardware Monitoring\n",
    "\n",
    "The workspace provides two pre-installed web-based tools to help developers during model training and other experimentation tasks to get insights into everything happening on the system and figure out performance bottlenecks.\n",
    "\n",
    "[Netdata](https://github.com/netdata/netdata) (`Open Tool -> Netdata`) is a real-time hardware and performance monitoring dashboard that visualize the processes and services on your Linux systems. It monitors metrics about CPU, GPU, memory, disks, networks, processes, and more.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/hardware-monitoring-netdata.png\" />\n",
    "\n",
    "[Glances](https://github.com/nicolargo/glances) (`Open Tool -> Glances`) is a web-based hardware monitoring dashboard as well and can be used as an alternative to Netdata.\n",
    "\n",
    "<img style=\"width: 100%\" src=\"https://github.com/ml-tooling/ml-workspace/raw/master/docs/images/features/hardware-monitoring-glances.png\"/>\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "Netdata and Glances will show you the hardware statistics for the entire machine on which the workspace container is running.\n",
    "</div>\n",
    "\n",
    "### Run as a job\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "A job is defined as any computational task that runs for a certain time to completion, such as a model training or a data pipeline.\n",
    "</div>\n",
    "\n",
    "The workspace image can also be used to execute arbitrary Python code without starting any of the pre-installed tools. This provides a seamless way to productize your ML projects since the code that has been developed interactively within the workspace will have the same environment and configuration when run as a job via the same workspace image.\n",
    "\n",
    "<details>\n",
    "<summary><b>Run Python code as a job via the workspace image</b> (click to expand...)</summary>\n",
    "\n",
    "To run Python code as a job, you need to provide a path or URL to a code directory (or script) via `EXECUTE_CODE`. The code can be either already mounted into the workspace container or downloaded from a version control system (e.g., git or svn) as described in the following sections. The selected code path needs to be python executable. In case the selected code is a directory (e.g., whenever you download the code from a VCS) you need to put a `__main__.py` file at the root of this directory. The `__main__.py` needs to contain the code that starts your job.\n",
    "\n",
    "#### Run code from version control system\n",
    "\n",
    "You can execute code directly from Git, Mercurial, Subversion, or Bazaar by using the pip-vcs format as described in [this guide](https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support). For example, to execute code from a [subdirectory](https://github.com/ml-tooling/ml-workspace/tree/master/resources/tests/ml-job) of a git repository, just run:\n",
    "\n",
    "```bash\n",
    "docker run --env EXECUTE_CODE=\"git+https://github.com/ml-tooling/ml-workspace.git#subdirectory=resources/tests/ml-job\" mltooling/ml-workspace:latest\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "📖 For additional information on how to specify branches, commits, or tags please refer to <a href=\"https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support\">this guide</a>.\n",
    "</div>\n",
    "\n",
    "#### Run code mounted into the workspace\n",
    "\n",
    "In the following example, we mount and execute the current working directory (expected to contain our code) into the `/workspace/ml-job/` directory of the workspace:\n",
    "\n",
    "```bash\n",
    "docker run -v \"${PWD}:/workspace/ml-job/\" --env EXECUTE_CODE=\"/workspace/ml-job/\" mltooling/ml-workspace:latest\n",
    "```\n",
    "\n",
    "#### Install Dependencies\n",
    "\n",
    "In the case that the pre-installed workspace libraries are not compatible with your code, you can install or change dependencies by just adding one or multiple of the following files to your code directory:\n",
    "\n",
    "- `requirements.txt`: [pip requirements format](https://pip.pypa.io/en/stable/user_guide/#requirements-files) for pip-installable dependencies.\n",
    "- `environment.yml`: [conda environment file](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html?highlight=environment.yml#creating-an-environment-file-manually) to create a separate Python environment.\n",
    "- `setup.sh`: A shell script executed via `/bin/bash`.\n",
    "\n",
    "The execution order is 1. `environment.yml` -> 2. `setup.sh` -> 3. `requirements.txt`\n",
    "\n",
    "#### Test job in interactive mode\n",
    "\n",
    "You can test your job code within the workspace (started normally with interactive tools) by executing the following python script:\n",
    "\n",
    "```bash\n",
    "python /resources/scripts/execute_code.py /path/to/your/job\n",
    "```\n",
    "\n",
    "#### Build a custom job image\n",
    "\n",
    "It is also possible to embed your code directly into a custom job image, as shown below:\n",
    "\n",
    "```dockerfile\n",
    "FROM mltooling/ml-workspace:latest\n",
    "\n",
    "# Add job code to image\n",
    "COPY ml-job /workspace/ml-job\n",
    "ENV EXECUTE_CODE=/workspace/ml-job\n",
    "\n",
    "# Install requirements only\n",
    "RUN python /resources/scripts/execute_code.py --requirements-only\n",
    "\n",
    "# Execute only the code at container startup\n",
    "CMD [\"python\", \"/resources/docker-entrypoint.py\", \"--code-only\"]\n",
    "```\n",
    "\n",
    "</details>\n",
    "\n",
    "### Pre-installed Libraries and Interpreters\n",
    "\n",
    "The workspace is pre-installed with many popular interpreters, data science libraries, and ubuntu packages:\n",
    "\n",
    "- **Interpreter:** Miniconda 3 (Python 3.6), Java 8, NodeJS 11\n",
    "- **Python libraries:** Tensorflow, Keras, Pytorch, Sklearn, CNTK, XGBoost, Theano, Fastai, and [many more](https://github.com/ml-tooling/ml-workspace/tree/master/resources/libraries)\n",
    "\n",
    "The full list of installed tools can be found within the [Dockerfile](https://github.com/ml-tooling/ml-workspace/blob/master/Dockerfile).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "For every minor version release, we run vulnerability, virus, and security checks within the workspace using <a href=\"https://vuls.io/\">vuls</a>, <a href=\"https://pyup.io/safety/\">safety</a>, and <a href=\"https://www.clamav.net/\">clamav</a> to make sure that the workspace environment is as secure as possible.\n",
    "</div>\n",
    "\n",
    "### Extensibility\n",
    "\n",
    "The workspace provides a high degree of extensibility. Within the workspace, you have **full root & sudo privileges** to install any library or tool you need via terminal (e.g., `pip`, `apt-get`, `conda`, or `npm`). You can open a terminal by one of the following ways:\n",
    "\n",
    "- **Jupyter:** `New -> Terminal`\n",
    "- **Desktop VNC:** `Applications -> Terminal Emulator`\n",
    "- **JupyterLab:** `File -> New -> Terminal`\n",
    "- **VS Code:** `Terminal -> New Terminal`\n",
    "\n",
    "Additionally, pre-installed tools such as Jupyter, JupyterLab, and Visual Studio Code each provide their own rich ecosystem of extensions. The workspace also contains a [collection of installer scripts](../tree/tools) for many commonly used development tools or libraries (e.g., `PyCharm`, `Zeppelin`, `RStudio`, `Starspace`). Those scripts can be either executed from the Desktop VNC (double-click on the script within the `Tools` folder on the Desktop) or from a terminal (execute any tool script from the `/resources/tools/` folder).\n",
    "\n",
    "<details>\n",
    "<summary>Example (click to expand...)</summary>\n",
    "\n",
    "For example, to install the [Apache Zeppelin](https://zeppelin.apache.org/) notebook server, simply execute:\n",
    "\n",
    "```bash\n",
    "/resources/tools/zeppelin.sh --port=1234\n",
    "```\n",
    "\n",
    "After installation, refresh the Jupyter website and the Zeppelin tool will be available under `Open Tool -> Zeppelin`. Other tools might only be available within the Desktop VNC (e.g., `atom` or `pycharm`) or do not provide any UI (e.g., `starspace`, `docker-client`).\n",
    "</details>\n",
    "\n",
    "As an alternative to extending the workspace at runtime, you can also customize the workspace Docker image to create your own flavor as explained in the [FAQ](https://github.com/ml-tooling/ml-workspace#faq) section.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-09-03T16:27:35.815571Z",
     "start_time": "2019-09-03T16:27:35.791132Z"
    }
   },
   "source": [
    "## Support"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ML Workspace project is maintained by [Lukas Masuch](https://twitter.com/LukasMasuch)\n",
    "and [Benjamin Räthlein](https://twitter.com/raethlein). Please understand that we won't be able\n",
    "to provide individual support via email. We also believe that help is much more\n",
    "valuable if it's shared publicly so that more people can benefit from it.\n",
    "\n",
    "\n",
    "<table align=\"left\" style=\"\">\n",
    "    <thead>\n",
    "        <th style=\"text-align: left;\">Type</th>\n",
    "        <th style=\"text-align: left; min-width: 300px;\">Channel</th>\n",
    "    </thead>\n",
    "    <tr>\n",
    "        <td style=\"text-align: left;\">🚨 Bug Reports</td>\n",
    "        <td style=\"text-align: left;\"><a href=\"https://github.com/ml-tooling/ml-workspace/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Abug+sort%3Areactions-%2B1-desc+\" title=\"Open Bug Report\"><img align=\"left\" src=\"https://img.shields.io/github/issues/ml-tooling/ml-workspace/bug.svg\"></a></td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <td style=\"text-align: left;\">🎁 Feature Requests</td>\n",
    "        <td style=\"text-align: left;\"><a href=\"https://github.com/ml-tooling/ml-workspace/issues?q=is%3Aopen+is%3Aissue+label%3Afeature-request+sort%3Areactions-%2B1-desc\" title=\"Open Feature Request\"><img align=\"left\" src=\"https://img.shields.io/github/issues/ml-tooling/ml-workspace/feature-request.svg?label=feature%20requests\"></a> </td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <td style=\"text-align: left;\">👩‍💻 Usage Questions</td>\n",
    "        <td style=\"text-align: left;\"><a href=\"https://stackoverflow.com/questions/tagged/ml-tooling\" title=\"Open Question on Stackoverflow\"><img align=\"left\" src=\"https://img.shields.io/badge/stackoverflow-ml--tooling-orange.svg\"></a> <a href=\"https://gitter.im/ml-tooling/ml-workspace\" title=\"Chat on Gitter\"><img align=\"left\" style=\"margin-left: 5px;\" src=\"https://badges.gitter.im/ml-tooling/ml-workspace.svg\"></a></td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "        <td style=\"text-align: left;\">🗯 General Discussion</td>\n",
    "        <td style=\"text-align: left;\"><div align=\"left\"><a href=\"https://gitter.im/ml-tooling/ml-workspace\" title=\"Chat on Gitter\"><img align=\"left\" src=\"https://badges.gitter.im/ml-tooling/ml-workspace.svg\"></a><a href=\"https://twitter.com/mltooling\" title=\"ML Tooling on Twitter\"><img align=\"left\" style=\"margin-left: 5px;\" src=\"https://img.shields.io/twitter/follow/mltooling.svg?style=social\"></a></div></td>\n",
    "    </tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- [Python Basics](./tutorials/python-basics-tutorial.ipynb): Learn the basics about python data types.\n",
    "- [Jupyter Tipps & Tricks](./tutorials/jupyter-tipps.ipynb): Explore some amazing functionalities that you can use with Jupyter within the workspace.\n",
    "- [Visualization in Jupyter](./tutorials/visualization-tutorial.ipynb): Introduction to data visualization with various common charting tools.\n",
    "- [Introduction to Pandas](./tutorials/pandas-tutorial.ipynb): Introduction to the data structures and functionalities of the pandas library."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.9"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": false,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": false,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
